Quick reference

(collected from James Harkins' tutorial)

Primary Patterns

• * Pseq(list, repeats, offset): Play through the entire list 'repeats' times. Like list.do.
• * Prand(list, repeats): Choose items from the list randomly (same as list.choose).
• * Pxrand(list, repeats): Choose randomly, but never repeat the same item twice.
• * Pshuf(list, repeats): Shuffle the list in random order, and use the same random order 'repeats' times. Like list.scramble.
• * Pwrand(list, weights, repeats): Choose randomly by weighted probabilities (like list.wchoose(weights)).

• * Pseries(start, step, length): Arithmetic series (addition).
• * Pgeom(start, grow, length): Geometric series (multiplication).

• * Pwhite(lo, hi, length): Random numbers, equal distribution ("white noise"). Like rrand(lo, hi).
• * Pexprand(lo, hi, length): Random numbers, exponential distribution. Like exprand(lo, hi).
• * Pbrown(lo, hi, step, length): Brownian motion, arithmetic scale (addition).

• * Pfunc(nextFunc, resetFunc): Get the stream values from a user-supplied function.
• * Pfuncn(func, repeats): Get values from the function, but stop after 'repeats' items.
• * Proutine(routineFunc): Use the function like a routine. The function should return values using .yield or .embedInStream.

Additional List Patterns

• Pser(list, repeats, offset): Play through the list as many times as needed, but output only 'repeats' items.
• Pslide(list, repeats, len, step, start, wrapAtEnd): Play overlapping segments from the list.

• Pwalk(list, stepPattern, directionPattern, startPos): Random walk over the list.

• Place(list, repeats, offset): Interlace any arrays found in the main list.
• Ppatlace(list, repeats, offset): Interlace any patterns found in the main list.
• Ptuple(list, repeats): Collect the list items into an array as the return value.

Additional Random Number Generators

• Pgbrown(lo, hi, step, length): Brownian motion, geometric scale (multiplication).

• Pbeta(lo, hi, prob1, prob2, length): Beta distribution, where prob1 = α (alpha) and prob2 = β (beta).
• Pcauchy(mean, spread, length): Cauchy distribution.
• Pgauss(mean, dev, length): Guassian (normal) distribution.
• Phprand(lo, hi, length): Returns the greater of two equal-distribution random numbers.
• Plprand(lo, hi, length): Returns the lesser of two equal-distribution random numbers.
• Pmeanrand(lo, hi, length): Returns the average of two equal-distribution random numbers, i.e., (x +  y) / 2.
• Ppoisson(mean, length): Poisson distribution.

• Pprob(distribution, lo, hi, length, tableSize): Arbitrary distribution, based on a probability table.

Random numbers and probability distributions

• Pwhite(lo, hi, length): Produces 'length' random numbers with equal distribution ('white' refers to white noise).
• Pexprand(lo, hi, length): Same, but the random numbers have an exponential distribution, favoring lower numbers. This is good for frequencies, and also durations (because you need more notes with a shorter duration to balance the weight of longer notes).
• Pbrown(lo, hi, step, length): Brownian motion. Each value adds a random step to the previous value, where the step has an equal distribution between -step and +step.
• Pgbrown(lo, hi, step, length): Brownian motion on a geometric scale. Each value multiplies a random step factor to the previous value.

• Pbeta(lo, hi, prob1, prob2, length): Beta distribution, where prob1 = α (alpha) and prob2 = β (beta).
• Pcauchy(mean, spread, length): Cauchy distribution.
• Pgauss(mean, dev, length): Guassian (normal) distribution.
• Phprand(lo, hi, length): Returns the greater of two equal-distribution random numbers.
• Plprand(lo, hi, length): Returns the lesser of two equal-distribution random numbers.
• Pmeanrand(lo, hi, length): Returns the average of two equal-distribution random numbers, i.e., (x + y) / 2.
• Ppoisson(mean, length): Poisson distribution.

• Pprob(distribution, lo, hi, length, tableSize): Given an array of relative probabilities across the desired range (a histogram) representing an arbitrary distribution, generates random numbers corresponding to that distribution.
• 
  
• Repetition and Constraint patterns

• Pclutch(pattern, connected): If the 'connected' pattern is true, Pclutch returns the next value from 'pattern'. If 'connected' is false, the previous pattern value is repeated. It's like a clutch in a car: when engaged, the pattern moves forward; when disconnected, it stays where it is.
• Pn(pattern, repeats): Embeds the source pattern 'repeats' times: simple repetition. This also works on single values: Pn(1, 5) outputs the number 1 5 times.
• Pstutter(n, pattern): 'n' and 'pattern' are both patterns. Each value from 'pattern' is repeated 'n' times. If 'n' is a pattern, each value can be repeated a different number of times.
• PdurStutter(n, pattern): Like Pstutter, except the pattern value is divided by the number of repeats (so that the total time for the repeat cycle is the duration value from the source pattern).

• Pfin(count, pattern): Returns exactly 'count' values from the source pattern, then stops.
• Pconst(sum, pattern, tolerance): Output numbers until the sum reaches a predefined limit. The last output value is adjusted so that the sum matches the limit exactly.
• Pfindur(dur, pattern, tolerance): Like Pconst, but applying the "constrain" behavior to the event's rhythmic values. The source pattern runs up to the specified duration, then stops. This is very useful if you know how long a musical behavior should go on, but the number of events to fill up that time is not known.
• Psync(pattern, quant, maxdur, tolerance): Like Pfindur, but does not have a fixed duration limit. Instead, it plays until either it reaches maxdur (in which case it behaves like Pfindur, adjusting the last event so the total duration matches maxdur), or the pattern stops early and the last event is rounded up to the next integer multiple of quant.

Time-based patterns

• Ptime(repeats): Returns the amount of time elapsed since embedding.
• Pstep(levels, durs, repeats): Repeat a 'level' value for its corresponding duration, then move to the next.
• Pseg(levels, durs, curves, repeats): Similar to Pstep, but interpolates to the next value instead of stepping abruptly at the end of the duration. Interpolation is linear by default, but any envelope segment curve can be used. Levels, durs and curves should be patterns.
• Related: Use of Env as a pattern.

Adding values into event patterns

(Or, "Pattern Composition")

• Pbindf(pattern, pairs): Adds new key-value pairs onto a pre-existing Pbind-style pattern.
• Pchain(patterns): Chains separate Pbind-style patterns together, so that all their key-value pairs go into the same event.

Parallelizing event patterns

• Ppar(list, repeats): Start each of the event patterns in the 'list' at the same time. When the last one finishes, the Ppar also stops. If repeats > 1, all the subpatterns start over again from the beginning.
• Ptpar(list, repeats): Here, the list consists of [timeOffset0, pattern0, timeOffset1, pattern1...]. Each pattern starts after the number of beats given as its time offset. The patterns can start at different times relative to each other.
• Pgpar(list, repeats): Like Ppar, but it creates a separate group for each subpattern.
• Pgtpar(list, repeats): This is supposed to be like Ptpar with separate groups for the sub patterns, but the class is currently broken.

• Pspawner(routineFunc): The function is used to make a routine. A Spawner object gets passed into this routine, and this object is used to add or remove streams to/from the parallel stream. New patterns can be added in sequence or in parallel.
• Pspawn(pattern, spawnProtoEvent): Supports most of the features of Pspawner, but uses a pattern to control the Spawner object instead of a routine function.

Language control methods

Some patterns mimic language-style control methods: conditionals (Pif), loops (Pwhile) and error cleanup (Pprotect).

• Pif(condition, iftrue, iffalse, default): Evaluates a pattern 'condition' that returns true or false. Then, one value is taken from the true or false branch before going back to evaluate the condition again. The 'default' value or pattern comes into play when the true or false branch stops producing values (returns nil). If the default is not given, Pif returns control to the parent upon nil from either branch.
• Pseed(randSeed, pattern): Random number generators depend on seed values; setting a specific seed produces a repeatable stream of pseudorandom numbers. Pseed sets the random seed before embedding 'pattern', effectively restarting the random number generator at the start of the pattern.
• Pprotect(pattern, func): Like the 'protect' error handling method, if an error occurs while getting the next value from the pattern, the function will be evaluated before the error interrupts execution.
• Ptrace(pattern, key, printStream, prefix): For debugging, Ptrace prints every return value. Is your pattern really doing what you think? This will tell you. A Ptrace is created automatically by the 'trace' message: aPattern.trace(key, printStream, prefix) --> Ptrace(aPattern, key, printStream, prefix).
• Pwhile(func, pattern): Like while: as long as the function evaluates to true, the pattern is embedded. The function is checked once at the beginning and thereafter when the pattern comes to an end. If it's applied to an infinite pattern, there's no looping because the pattern never gives control back.

Server control methods

• Pbus(pattern, dur, fadeTime, numChannels, rate): Creates a private group and bus for the synths played by the pattern. The group and bus are released when the pattern stops. Useful for isolating signals from different patterns.
• Pgroup(pattern): Creates a private group (without private bus) for the pattern's synths.

• Pfx(pattern, fxname, pairs)
• Pfxb(pattern, fxname, pairs): Both of these patterns play an effect synth at the tail of the target group. This synth should read from the bus identified by the 'out' argument, and write the processed signal onto the same bus using either ReplaceOut or XOut. Pfx uses whatever bus and group are specified in the incoming event. Pfxb allocates a separate bus and group for the effect and the pattern.

• Pproto(makeFunction, pattern, cleanupFunc): Allocate resources on the server and add references to them into the event prototype used to play 'pattern'. When the pattern stops (or is stopped), the resources can be removed automatically.

Data sharing

• Pkey(key): Read the 'key' in the input event, making previously-calculated values available for other streams.
• Penvir(envir, pattern, independent): Run the pattern inside a given environment.
• Pfset(func, pattern): Assign default values into the input event before getting each result event out of the given pattern.
• Plambda(pattern, scope): Creates a "function scope" into which values are assigned using Plet, and from which values are retrieved with Pget. Pget is somewhat like Pkey, except that its scope is strictly internal, hidden from the caller. With Pkey, the source values remain present in the event returned to the caller.
• 
  

Pset and cousins

A group of pattern classes allow single event keys to be overwritten, or one addition or multiplication to be performed. Pkey, in combination with the Pchain or Pbindf "pattern composition" classes, can do everything the following classes can do (though this alternate notation may be more convenient in certain cases).

• Pset(name, value, pattern): Get one event from 'pattern', and then put the next value from the 'value' pattern into the 'name' key. If the source pattern specifies a value for the same name, the value from the source will be replaced with the new one.

• Padd(name, value, pattern): After getting the next event, replace the 'name' value with its existing value + the next number from 'value'.

• Pmul(name, value, pattern): After getting the next event, replace the 'name' value with its existing value * the next number from 'value'.